<html>
	<head>
		<title>Perforce Operations</title>
		<link rel="STYLESHEET" href="book.css" charset="ISO-8859-1" type="text/css" />
	</head>
	<body>
		<h2>Perforce Operations</h2>
		
		<p>
			This section of the user guide will describe the way in which the various 
			Perforce operations can be performed from within eclipse, using the p4eclipse
			plugin.
		</p>
		<p>
			The p4 eclipse plugin uses functionality provided by the Eclipse team framework to enable 
			the use of the perforce source code management system. This means that if you are already 
			familiar with the CVS Team plugin, you will encounter similarities.
		</p>
		<div>
			The following operations will be discusssed below:
			<ul>
				<li><b><a href="#ProjectSetup">Project setup</a></b>
					<ul>
						<li>
							<a href="#CheckoutProject">Check out a project</a>
						</li>
						<li>
							<a href="#ShareNewProject">Share a new project</a>
						</li>
						<li>
							<a href="#ConnectExistingProject">
								Connect to an existing project
							</a>
						</li>
					</ul>
				</li>
				<li><b><a href="#FileOperations">File operations</a></b>
					<ul>
						<li>
							<a href="#AddToSourceControl">Add to source control</a>
						</li>
						<li>
							<a href="#OpenForEdit">Open for Edit</a>
						</li>
						<li>
							<a href="#OpenForDelete">Open for Delete</a>
						</li>
					</ul>
				</li>
				<li><b><a href="#Depot">Staying in touch with the depot</a></b>
					<ul>				
						<li>
							<a href="#SyncToHead">Sync to Head revision</a>
						</li>
						<li>
							<a href="#SubmitChangelist">Submit changelist</a>
						</li>
						<li>
							<a href="#EditChangelist">Edit changelists</a>
						</li>
						<li>
							<a href="#ResolveConflict">Resolve a conflict</a>
						</li>
						<li>
							<a href="#CompareOperations">Compare operations</a>
						</li>
						<li>
							<a href="#RevisionHistory">Revision history</a>
						</li>
					</ul>
				</li>
			</ul>
		</div>
		
		<h3><a name="ProjectSetup">Project Setup</a></h3>
		
		<p>
			There are several ways to start working with a perforce client view in Eclipse. This section will
			explain how to check out a project from perforce into Eclipse, how to share a project you have 
			made within Eclipse that does not yet have a counterpart in the Perforce depot and how to
			connect your client depot to an existing perforce client view.
		</p>
		
		<a name="CheckoutProject">&nbsp;</a>
		<div class="stepList">
		<h4>Check out a project</h4>
	    <ol>
    		<li>
			<b>Open the <a href="Perspective.html">Perforce Perspective</a></b> - 
			The easiest way to open the perspective, is using the menu 
			<span class="menu">Window->Open&nbsp;Perspective->Perforce</span>. If the Perforce 
			menu entry is not available, select <span class="menu">Other...</span>, and select Perforce
				from the given list.
			</li>
			<li>
				<b>Select the <i>Client View of Perforce Depot</i></b>
			</li>
	    		<li>
				<b>Right click</b> in this view and select <span class="menu">New->Perforce Server</span>
			</li>
		 	<li>
				<b>Define your <a href="Perspective.html#PerforceServer">Perforce Server</a></b>

    			<p> At this point, your <i>Client View of Perforce Depot</i> should show a tree 
			with the root node identifying the Perforce Server you've just created.</p>
			</li>
	    		
			<li>
				<b>Expand the Server node</b> by clicking on the triangle to the left.  You should see
				two child nodes, one for <i>Depots</i>, and one for <i>Projects</i>
			</li>
	       		<li>
				<b>Browse the depot</b>, looking for your project in the depot.
			</li>
	       		<li>
				<b>Checkout As Project</b> - right click on the folder containing your project and select 
				<span class="menu">Check Out as Project</span>  

				<p><b>Note</b>: if you do not have an Eclipse .project file in this folder, one will be created 
				for you.  If you use <span class="menu">Check Out as ...</span> you will be allowed to
				specify a name for your project. )
				</p>
			</li>
	    </ol>

   <p>Your project is now checked out of the Perforce depot and added to Eclipse.</p>
	   </div>

		<a name="ShareNewProject">&nbsp;</a>
	   <div class="stepList">
	   <h4>Share a new Project</h4>
	   <ol>
   		<li>
			<b>Select <span class="menu">Team->Share Project</span> </b> - to do this, right click on
			the project</li>
  		<li><b>Select Perforce</b> and the press <span class="button">Next.</span></li>
   		<li><b>Select <span class="button">New Server...</span></b></li>
	    	<li><b>Define your <a href="Perspective.html#PerforceServer">Perforce Server</a></b> 	</li>
	    	<li><b>Adjust the location</b> of your project.  If your project is not under your 
		Perforce client root, then you need to enter a	new location that is (your project will be moved
		for you), or edit your Perforce client outside of Eclipse (restarting Eclipse after the edit may be 
		necessary).</li>
	     <li><b>Click Finish</b> Your project is now connected to the Perforce Depot</li>
	     <li>
			<b>Add</b> your project to source control, 
			using <span class="menu">Team-><a href="#AddToSourceControl">Add to Source Control</a>
			</span> on resources in your project.
		</li>
	  </ol>
	   </div>

	<a name="ConnectExistingProject">&nbsp;</a>
	<div class="stepList">
	<h4>Connect to an existing project</h4>
	<ol>
		<li>
			<b>Select <span class="menu">Team->Share Project</span> </b> - to do this, right click on 
			the project
		</li>
	   	<li>
			<b>Select Perforce</b> and the press <span class="button">Next.</span>
		</li>
	   	<li>
			<b>Select <span class="button">New Server...</span></b>
		</li>
	    	<li><b>Define your <a href="Perspective.html#PerforceServer">Perforce Server</a></b></li>
	     	<li><b>Click Finish</b> Your project is now connected to the Perforce Depot</li>
	  </ol>
	   </div>

	<h3><a name="FileOperations">File operations</a></h3>
	
	<p>
		P4eclipse allows you to perform the common perforce operations <a href="#AddToSourceControl">Add
		To Source Control</a>, <a href="#OpenForEdit">Open For Edit</a> and 
		<a href="#OpenForDelete">Open for Delete</a> on the files in your project.
	</p>

	<a name="AddToSourceControl">&nbsp;</a>
	<div class="stepList">
	<h4>Add to source control</h4>
	<ol>
		<li><b>Right click</b> on the file you wish to add to Perforce.</li>
		<li><b>Select <span class="menu">Team->Add&nbsp;to&nbsp;source&nbsp;control</span>.</b></li>
	</ol>
	<p>Your file is now added to your default changelist as new file.</p>
	</div>

	<a name="OpenForEdit">&nbsp;</a>
	<div class="stepList">
	<h4>Open for edit</h4>
	<ol>
		<li><b>Right click</b> on the file you wish edit.</li>
		<li><b>Select <span class="menu">Team->Open&nbsp;for&nbsp;Edit</span>.</b></li>
	</ol>
	<p>
		Your file is registered with the perforce server as opened by you, and automatically added to your 
		default changelist.
	</p>
	<p>
		<b>Note</b>: It is possible to let p4eclipse automatically open files you for editing, when you change a file
		 under Perforce control, by choosing the option 'Automatically open files on edit' in the <span
		class="menu">Team->Perforce</span> preferences.
	</p>
	</div>

	<a name="OpenForDelete">&nbsp;</a>
	<div class="stepList">
	<h4>Open for delete</h4>
	<p>
		P4eclipse will transparently open file for delete when you delete a file that is under Perforce control.
	</p>
	<ol>
		<li><b>Right click</b> on the file you wish to delete from the Perforce depot.</li>
		<li><b>Select <span class="menu">Delete</span>.</b></li>
	</ol>
	<p>Your file is now added to your default changelist as deleted, and removed from your client.</p>
	</div>

	<h3><a name="Depot">Staying in touch with the depot</a></h3>
	
	<p>
		When working with files under source control, it is important to keep your local copies in sync with the
		server. With p4eclipse, most operations keep your files up-to-date, and manage your changelists are
		available from within eclipse.
	</p>
	<p>
		It is possible to <a href="#SyncToHead">synchronize your file to the head revision</a>, 
		<a href="#EditChangelist">edit</a> and <a href="SubmitChangelist">submit</a> a changelist, 
		<a href="#ResolveConflict">resolve conflicts</a> and <a href="#CompareOperations">compare</a> 
		a file to a different version.
	</p>

	<a name="SyncToHead">&nbsp;</a>
	<div class="stepList">
	<h4>Sync to Head revision</h4>
	<ol>
		<li><b>Right click</b> on the file you wish to synch.</li>
		<li><b>Select <span class="menu">Team->Synch&nbsp;to&nbsp;Head&nbsp;Revision</span>.</b></li>
	</ol>
	<p>Your file is now synchronized to the depot.</p>
	</div>

	<a name="SubmitChangelist">&nbsp;</a>
	<div class="stepList">
	<h4>Submit changelist</h4>
	<ol>
		<li><b>Select the <i>Pending Changelists</i> view</b>.</li>
		<li>
			<b>Expand the node corresponding to <i>Perforce Server</i> you want to submit a changelist 
			for.</b>
		</li>
		<li>
			<b>Expand the <i>Pending Changelists></i>  node.</b>
			<p >
				You will now see a list of the changelists that you currently have open for this client view.  By 		
				expanding the tree further you can view the contents of those changelists, and 
				<a href="EditChangelist">edit</a> them.
			</p>
		</li>
		<li><b>Right click</b> on the changelist you wish to submit.</li>
		<li><b>Select <span class="menu">Submit...</span>.</b>  - The
			 <i>Perforce Change Specification</i> dialog will appear.
			<p>
				<!-- move this to a more detailed description of the Change Spec dialog in the Perspective page -->
				You can now enter a description for the changelist, and select which files in the changelist will be
				submitted
			</p>
			</li>


		<li>
			<b>Enter a description for the changelist</b> - If you selected the default changelist, this is
			mandatory, the default value must be changed.
		</li>
		<li><b>Click on <span class="button">Submit</span></b> 
			or <span class="button">Cancel</span> if you've changed your mind.</li>
	</ol>
	<p>
		Your changelist is now submitted to the perforce depot. If there were any problems during the submittal,
		 you will be notified of them so that you can <a href="#ResolveConflict">resolve any conflicts</a>.
	</p>
	</div>

	<a name="EditChangelist">&nbsp;</a>
	<div class="stepList">
	<h4>Edit changelists</h4>
		<div><b>Select the <i>Pending Changelists</i> view</b>.
			<ol>
				<li>
					<b>Expand the node corresponding to <i>Perforce Server</i> you want to edit a changelist 
					for.</b>
				</li>
				<li>
					<b>Expand the <i>Pending Changelists></i>  node.</b>
					<p>
						There are a number of operations that can be performed on changelists. It is possible to move files
						between changelists (simply drag and drop the files), revert files, automatically revert all unchanged
						files, and create new changelists.
					</p>
				</li>
			</ol>
		</div>
	<ul>
		<li>
			<div class="command">Create new changelist</div>
			<ol>
				<li><b>Right click</b> on the default changelist.</li>
				<li><b>Select <span class="menu">New Changelist...</span></b> - The
				 <i>Perforce Change Specification</i> dialog will appear.
				<p>
					<!-- move this to a more detailed description of the Change Spec dialog in the Perspective page -->
					You can now enter a description for the changelist, and select which files from the default
					changelist should be moved to the new changelist.
				</p>
				</li>
	
				<li>
					<b>Enter a description for the changelist</b> - This is
					mandatory, the default value must be changed.
				</li>
				<li><b>Click on <i>Update</i></b> - your new changelist will appear in the list.</li>
			</ol>
		</li>
		<li>
			<div class="command">Revert all unchanged files</div>
			<ol>
				<li><b>Right click</b> on a changelist</li>
				<li><b>Select <span class="menu">Revert&nbsp;Unchanged&nbsp;Files</span></b>
				<p>All files that were unchanged will be reverted, and thus removed from the changelist.</p>
				</li>
			</ol>
		</li>
		<li>
			<div class="command">Revert a file</div>
			<ol>
				<li><b>Right click</b> on the file you wish to revert in the changelist.</li>
				<li><b>Select <span class="menu">Revert</span></b> - a warning dialog will appear, warning 
					you that you will lose any edits on the file if you revert
				<p><b>Note</b>: You <i>will</i> lose your changes if you revert a file!</p>
					</li>
	
				<li><b>Select <i>Ok</i> to revert the file.</b></li>
			</ol>
		</li>
	</ul>
	</div>

	<h4><a name="ResolveConflict">Resolve a conflict</a></h4>
	
	<p>
		If you have edited a file that on which changes have been submitted to the depot by another
		user since your last synch, there is a conflict, which will have to be resolved before you can 
		commit your own changes to the depot.
	</p>
	<p>
		P4eclipse will notify you of a conflict when you synch, or when you try to submit a changelist
		containing files wilt a conflict. Furthermore, if the project is also included when performing 
		background updates, a file in conflict will be marked with a yellow exclamation mark.
	</p>
	<p>
		A conflict can be resolved in different ways. You can <b>revert</b> the file, overwriting your 
		own changes with the version from the depot. You can also decide to overwrite the changes 
		already in the depot with the version you have changed. And of course it's possible to merge 
		the two versions, either automatically, or manually using the eclipse compare view.
	</p>

	<p>
		<b>Note:</b> If you want to resolve a file that is not marked as being in conflict, it
		 is possible to force this by right-clicking the file and selecting 
		<span class="menu">Resolve->Schedule File for Resolve</span>.
	</p>

	<a name="revert">&nbsp;</a>
	<div class="stepList">
	<h3>Revert a file</h3>
	<p>
		Reverting a file is the simplest way of solving a conflict, discarding all your changes, and
		overwriting the local file with the version from the depot.
	</p>
	<ol>
		<li><b>Select the <i>Pending Changelists view</i></b>.</li>
		<li><b>Right click on the file in conflict</b>. - Files in conflict will be marked with a yellow
		exclamation mark. </li>
		<li><b>Select <span class="menu">Revert</span></b></li>
	</ol>
	</div>
	
	<a name="ManuallyResolve">&nbsp;</a>
	<div class="stepList">
	<h3>Manually Resolve</h3>
	<p>
		Manually resolving a file will bring up the <i>Eclipse Compare view</i> where you can compare
		your version of the file against the version in the depot. For detailed information about the compare
		view, see <a href="CompareOperations">Compare Operations</a>.
	</p>	
	<ol>
		<li><b>Select the <i>Pending Changelists view</i></b>.</li>
		<li><b>Right click on the file in conflict</b>. - Files in conflict will be marked with a yellow
		exclamation mark. </li>
		<li><b>Select <span class="menu">Resolve->Manually</span></b> - The <i>Eclipse Compare view</i>
		will appear.</li>
		<li><b>Merge the changes</b> into your local file using the normal <a href="CompareOperations">
		compare operations</a>.</li>
		<li><b>Right click on the filename in the <i>Structure Compare</i> section and select 
		<span class="menu">Mark as Resolved</span></b> - Your file will no longer be marked as scheduled
		for resolve, and when you commit the changelist the merged version from your client view will be 
		committed to the depot.</li>		
	</ol>
	</div>

	<a name="revert">&nbsp;</a>
	<div class="stepList">
	<h3>Auto Resolve</h3>
	<ol>
		<li><b>Select the <i>Pending Changelists view</i></b>.</li>
		<li><b>Right click on the file in conflict</b>. - Files in conflict will be marked with a yellow
		exclamation mark. </li>
		<li><b>Select <span class="menu">Resolve->Auto&nbsp;Resolve</span></b> -  
		The <i>Auto Resolve</i> dialog will appear.
		
		<p>
			The <i>Auto Resolve</i> dialog offers five different options for the automatic
			resolving of the conflict:
					</p>
			<table>
				<tr valign="top">
					<td>
						<b>Accept theirs</b>
					</td>
					<td>
						Accept the changes coming in from the depot, overwriting all your own changes.
					</td>
				</tr>
				<tr valign="top">
					<td>
						<b>Accept yours</b>
					</td>
					<td>
						Overwrite the incoming changes with your version.
					</td>
				</tr>
				<tr valign="top">
					<td>
						<b>Safe Automatic Resolve</b>
					</td>
					<td>
						Use the incoming changes for files where your version is unchanged, outgoing 
						changes for files where the depot version hasn't changed, and skip all files where
						both versions have changed. 
					</td>
				</tr>
				<tr valign="top">
					<td>
						<b>Automatic Resolve</b>
					</td>
					<td>
						The same as the <i>Safe Automatic Resolve</i> except that when both versions
						of the file have changed, the changes are merged into the local file so you can
						examine them and resolve any problems.
					</td>
				</tr>
				<tr valign="top">
					<td>
						<b>Automatic Resolve, including conflict markers</b>
					</td>
					<td>
						Merge all versions into one file, marking what was in the original 
						(common ancestor), what was changed by the other, and what was 
						changed by you. Then you can edit the file to you liking, and mark it resolved.
					</td>
				</tr>
			</table>

		</li>
	</ol>
	</div>

	<h4><a name="CompareOperations">Compare operations</a></h4>
	<p>
		The p4eclipse plugin integrates with the eclipse comparison functionality to allow you 
		to compare the files in your client view with the versions in the depot. This can be either 
		by directly comparing against the <a href="#CompareHead">HEAD revision</a>, or by
		comparing with any <a href="#CompareRevision">revision</a> in the depot.
	</p>

	<a name="CompareHead">&nbsp;</a>
	<div class="stepList">
	<h3>Compare against HEAD Revision</h3>
	<ol>
		<li>
			<b>Right click on the file you want to compare</b> and select 
			<span class="menu">Compare&nbsp;with->HEAD&nbsp;Revision</span>
		<p>
			The <i>eclipse compare view</i> will be opened with the selected file and its depot version so that
			you can compare and merge the versions.
		</p>
		</li>
	</ol>
	</div>

	<a name="CompareRevision">&nbsp;</a>
	<div class="stepList">
	<h3>Compare against any revision</h3>
	<ol>
		<li>
			<b>Right click on the file you want to compare</b> and select 
			<span class="menu">Compare&nbsp;with->Revision...</span>
		<p>
			A <i>eclipse compare view</i> will be opened with a section listing all revisions of the selected 
			file that are available in the depot. By <b>double-clicking</b> a revision in the list, that revision
			will be loaded as the <i>repository file</i> in the compare view, so that you can compare it to your
			workspace version.
		</p>
		</li>
	</ol>
	</div>

	<a name="RevisionHistory">&nbsp;</a>
	<div class="stepList">
	<h4>Revision history</h4>
	<p>
		P4eclipse can show the revision history of a file, showing when what changes were done by whom, 
		and maybe (if the comment is useful) why.
	</p>
	<ol>
		<li>
			In the <i>Navigator</i> or the <i>Package Explorer</i>, <b>right click</b> on the file you wish 
			to see the revision history of, and select 
			<span class="menu">Team->Show&nbsp;in&nbsp;Revision&nbsp;History</span>.
			Or, in the <i>Client View of Perforce Depot</i>, the context menu entry is directly
			<span class="menu">Show&nbsp;in&nbsp;Revision&nbsp;History</span>.
		<p>
			The Revision History view that is shown is divided into three sections. The upper section is the
			list of revisions for the selected file, the lower left displays the action that was performed on the
			file for the selected revision, and on the lower right side the comment for that revision is printed.
		</p>
		</li>
	</ol>
	</div>

</body>
</html>